@Part[Array, Root = "CLM.MSS"]
@Comment{Chapter of Common Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇


@MyChapter[Arrays]

An array is an object with components arranged according
to a rectilinear coordinate system.
In principle, an
array in @clisp may have any number of dimensions, including zero.
(A zero-dimensional array has exactly one element.)
In practice, an implementation may limit the number of dimensions
supported, but
every @clisp implementation must support arrays of up to
seven dimensions.
Each dimension is a non-negative integer; if any dimension of an array is zero,
the array has no elements.

An array may be a @def[general array], meaning each element may be any @xlisp
object, or it may be a @def[specialized array], meaning that each element
must be of a given restricted type.

One-dimensional arrays are called vectors.  General vectors may contain
any @xlisp object.  Vectors whose elements are restricted to type
@f[string-char] are called @i[strings].  Vectors whose elements are
restricted to type @f[bit] are called @i[bit-vectors].

@Section[Array Creation]

Do not be daunted by the many options of the function @f[make-array]!
All that is required to construct an array is a list of
the dimensions; most of the options are for relatively esoteric
applications.

@Defun[Fun {make-array⎇, Args {@i[dimensions]⎇, Keys = {[element-type][initial-element]⎇,
 MoreKeys = {[initial-contents][adjustable][fill-pointer]⎇,
 YetMoreKeys = {[displaced-to][displaced-index-offset]⎇,
 SuppressKeyIndex Yes]
This is the primitive function for making arrays.  The @i[dimensions] argument
should be a list of non-negative integers
that are to be the dimensions of the array; the
length of the list will be the dimensionality of the array.  
Each dimension must be smaller than @conref[array-dimension-limit],
and the product of all the dimensions must be smaller than
@Conref[array-total-size-limit].
Note that if @i[dimensions] is @nil then a zero-dimensional array is created.
For convenience when making a one-dimensional array, the single dimension
may be provided as an integer rather than a list of one integer.

An implementation of @clisp may impose a limit on the rank of an array,
but this limit may not be smaller than 7.  Therefore, any @clisp
program may assume the use of arrays of rank 7 or less.
The implementation-dependent limit on array rank is reflected in
@Conref[array-rank-limit].

The keyword arguments for @f[make-array] are as follows:
@Keywordlist[make-array]
@keyword[element-type]
This argument
should be the name of the type of the elements of the array;
an array is constructed
of the most specialized type that can nevertheless accommodate
elements of the given type.
The type @true specifies a general array, one whose elements may
be any @xlisp object; this is the default type.
@endkeyword

@keyword[initial-element]
This argument
may be used to initialize each element of the array.  The value
must be of the type specified by the @Kwd[element-type] argument.  If the
@Kwd[initial-element] option is omitted, the initial values of the array
elements are undefined (unless the @Kwd[initial-contents] or
@Kwd[displaced-to] option is used).
The @Kwd[initial-element] option may not be used with the
@Kwd[initial-contents] or @Kwd[displaced-to] option.
@endkeyword

@keyword[initial-contents]
This argument may be used to initialize the
contents of the array.  The value is a nested structure of sequences.  If
the array is zero-dimensional, then the value specifies the single
element.  Otherwise, the value must be a sequence whose length is equal
to the first dimension; each element must be a nested structure for an
array whose dimensions are the remaining dimensions, and so on.
For example:
@lisp
(make-array '(4 2 3) :initial-contents
	    '(((a b c) (1 2 3))
	      ((d e f) (3 1 2))
	      ((g h i) (2 3 1))
	      ((j k l) (0 0 0))))
@Endlisp
The numbers of levels in the structure must equal the rank of the array.
Each leaf of the nested structure
must be of the type specified by the @f[:type] option.  If the
@Kwd[initial-contents] option is omitted, the initial values of the array
elements are undefined (unless the @Kwd[initial-element] or
@Kwd[displaced-to] option is used).
The @Kwd[initial-contents] option may not be used with the
@Kwd[initial-element] or @Kwd[displaced-to] option.
@endkeyword

@keyword[adjustable]
This argument, if specified and not @false, indicates that it
must be possible to alter the array's size dynamically after it is
created.  This argument defaults to @nil.
@endkeyword

@keyword[fill-pointer]
This argument
specifies that the array should have a fill pointer.
If this option is specified and not @false, the array must be one-dimensional.
The value is used to initialize the fill pointer for the array.
If the value @true is specified, the length of the array is used;
otherwise the value must be an integer between 0 (inclusive)
and the length of the array (inclusive).
This argument defaults to @nil.
@endkeyword

@keyword[displaced-to]
This argument, if specified and
not @false, specifies that the array will be a @i[displaced] array.
The argument must then be an array;
@f[make-array] will create
an @i[indirect] or @i[shared] array that shares its contents with
the specified array.  In this case the @Kwd[displaced-index-offset]
option may be useful.
@Index[displaced array]
@Index[shared array]
@Index[indirect array]
It is an error if the array specified as the @Kwd[displaced-to] argument
does not have the same @Kwd[element-type] as the array being created.
The @Kwd[displaced-to] option may not be used with the @Kwd[initial-element]
or @Kwd[initial-contents] option.
This argument defaults to @nil.
@endkeyword

@keyword[displaced-index-offset]
This argument may be used only in conjunction
with the @f[displaced-to] option.
It must be a non-negative integer (it defaults to zero); it is made to be the
index-offset of the created shared array.
@Index[index offset]

When an array A is given as
the @Kwd[displaced-to] argument to @f[make-array] when creating array B,
then array B is said to be @i[displaced] to array A.  Now the
total number of elements in an array, called the @i[total size] of the array,
is calculated as the product of all the dimensions
(see @Funref[array-total-size]).
It is required that the total size of A be no smaller than the sum
of the total size of B plus the offset @i[n] specified by
the @Kwd[displaced-index-offset]
argument.  The effect of displacing is that array B does not have any
elements of its own, but instead maps accesses to itself into
accesses to array A.  The mapping treats both arrays as if they
were one-dimensional by taking the elements in row-major order,
and then maps an access to element @i[k] of array B to an access to element
@i[k]+@i[n] of array A.
@endkeyword
@Endkeywordlist

If @f[make-array] is called with the @Kwd[adjustable], @Kwd[fill-pointer],
and @Kwd[displaced-to]
arguments each either unspecified or @nil, then the
resulting array is guaranteed to be a @i[simple] array.
(See section @ref[ARRAY-TYPE-SECTION].)

Here are some examples of the use of @f[make-array]:
@lisp
;; @r[Create a one-dimensional array of five elements.]
(make-array 5)

;; @r[Create a two-dimensional array, 3 by 4, with four-bit elements.]
(make-array '(3 4) @Kwd[element-type] '(mod 16))

;; @r[Create an array of single-floats.]
(make-array 5 @Kwd[element-type] 'single-float))
@Endlisp

@Lisp
;; @r[Making a shared array.]
(setq a (make-array '(4 3)))
(setq b (make-array 8 :displaced-to a
		      :displaced-index-offset 2))
;; @r[Now it is the case that:]
	(aref b 0) @EQ (aref a 0 2)
	(aref b 1) @EQ (aref a 1 0)
	(aref b 2) @EQ (aref a 1 1)
	(aref b 3) @EQ (aref a 1 2)
	(aref b 4) @EQ (aref a 2 0)
	(aref b 5) @EQ (aref a 2 1)
	(aref b 6) @EQ (aref a 2 2)
	(aref b 7) @EQ (aref a 3 0)
@Endlisp
The last example depends on the fact that arrays are, in effect,
stored in row-major order for purposes of sharing.  Put another way,
the indices for the elements of an array are ordered
lexicographically.
@Incompatibility{Both @lmlisp, as described in reference @cite[BLUE-LISPM],
and @c[fortran] @cite[DRAFT-FORTRAN-77, ANSI-FORTRAN-77] store arrays in
column-major order.⎇
@Enddefun

@Defcon[Var {array-rank-limit⎇]
The value of @f[array-rank-limit] is a positive integer that is
the upper exclusive bound on the rank of an array.
This bound depends on the implementation
but will not be smaller than 8; therefore every @clisp implementation
supports arrays whose rank is between 0 and 7 (inclusive).
(Implementors are enouraged to make this limit as large as practicable
without sacrificing performance.)
@Enddefcon

@Defcon[Var {array-dimension-limit⎇]
The value of @f[array-dimension-limit] is a positive integer that is
the upper exclusive bound on each individual dimension of an array.
This bound depends on the implementation
but will not be smaller than 1024.
(Implementors are enouraged to make this limit as large as practicable
without sacrificing performance.)
@Enddefcon

@Defcon[Var {array-total-size-limit⎇]
The value of @f[array-total-size-limit] is a positive integer that is
the upper exclusive bound on the total number of elements in an array.
This bound depends on the implementation
but will not be smaller than 1024.
(Implementors are enouraged to make this limit as large as practicable
without sacrificing performance.)

The actual limit on array size imposed by the implementation may vary
according the @Kwd[element-type] of the array; in this case the value of
@f[array-total-size-limit] will be the smallest of these individual
limits.
@Enddefcon

@Defun[Fun {vector⎇, Args {@rest @i[objects]⎇]
The function @f[vector] is a convenient means for creating
a simple general vector with specified initial contents.
It is analogous to the function @f[list].
@lisp
(vector @i[a]@-[@subr[1]] @i[a]@-[@subr[2]] ... @i[a]@-[@subi[n]])
   @EQ (make-array (list @i[n]) :element-type t
	     :initial-contents (list @i[a]@-[@subr[1]] @i[a]@-[@subr[2]] ... @i[a]@-[@subi[n]]))
@endlisp
@Enddefun

@Section[Array Access]

The function @f[aref] is normally
used for accessing an element of an array.
Other access functions, such as @f[svref], @f[char], and @f[bit]
may be more efficient in specialized circumstances.

@Defun[Fun {aref⎇, Args {@i[array] @rest @i[subscripts]⎇]
This accesses and returns the element of @i[array] specified
by the @i[subscripts].  The number of subscripts must
equal the rank of the array, and each subscript must be
a non-negative integer less than the corresponding array dimension.

@f[aref] is unusual among the functions that operate on arrays
in that it completely ignores fill pointers.  @f[aref] can access
without error any array element, whether active or not.  The generic
sequence function @Funref[elt], however, observes the fill pointer;
accessing an element beyond the fill pointer with @f[elt] is an error.

@Macref[setf] may be used with @f[aref] to destructively replace
an array element with a new value.

Under some circumstances it is desirable to write code that
will extract an element from an array @f[a] given a list @f[z] of the indices,
in such a way that the code works regardless of the rank of the
array.  This is easy using @Funref[apply]:
@lisp
(apply #'aref a z)
@endlisp
(The length of the list must of course equal the rank of
the array.)  This construction may be used with @f[setf] to alter
the element so selected to some new value @f[w]:
@lisp
(setf (apply #'aref a z) w)
@endlisp
@Enddefun

@Defun[Fun {svref⎇, Args {@i[simple-vector] @i[index]⎇]
The first argument must be a simple general vector,
that is, an object of type @f[simple-vector].
The element of the @i[simple-vector] specified by the integer @i[index]
is returned.  The @i[index] must be non-negative and less than
the length of the vector.

@Macref[setf] may be used with @f[svref] to destructively replace
a simple-vector element with a new value.

@f[svref] is identical to @Funref[aref] except that it requires its first
argument to be a simple vector.  In some implementations of @clisp,
@f[svref] may be faster than @f[aref] in situations where it is applicable.
See also @Funref[schar] and @Funref[sbit].
@Enddefun

@Section[Array Information]

The following functions extract from an array
interesting information other than the elements.

@Defun[Fun {array-element-type⎇, Args {@i[array]⎇]
@f[array-element-type] returns a type specifier for the set of objects
that can be stored in the @i[array].  This set may be larger than the
set requested when the array was created; for example,
the result of
@lisp
(array-element-type (make-array 5 :element-type '(mod 5)))
@endlisp
could be @f[(mod 5)], @f[(mod 8)], @f[fixnum], @f[t], or any other
type of which @f[(mod 5)] is a subtype.  See @Funref[subtypep].
@Enddefun

@Defun[Fun {array-rank⎇, Args {@i[array]⎇]
This returns the number of dimensions (axes) of @i[array].
This will be a non-negative integer.
See @Conref[array-rank-limit].
@Incompatibility{In @lmlisp, this is called @f[array-#-dims].
This name causes problems in other @xlisp dialects
because of the @f[#] character.⎇
@Enddefun

@Defun[Fun {array-dimension⎇, Args {@i[array] @i[axis-number]⎇]
The length of dimension number @i[axis-number] of the @i[array] is returned.
@i[array] may be any kind of array, and @i[axis-number] should
be a non-negative integer less than the rank of @i[array].
If the @i[array] is a vector with a fill pointer,
@f[array-dimension] returns the total size of the vector,
including inactive elements,
not the size indicated by the fill pointer.
(The function @Funref[length] will return the size indicated
by the fill pointer.)

@Incompatibility{This is similar to the @lmlisp function
@f[array-dimension-n], but takes its arguments in the other
order, and is zero-origin for consistency
instead of one-origin.  In @lmlisp @f[(array-dimension-n 0)]
returns the length of the array leader.⎇
@Enddefun

@Defun[Fun {array-dimensions⎇, Args {@i[array]⎇]
@f[array-dimensions] returns a list whose elements are the dimensions
of @i[array].
@Enddefun

@Defun[Fun {array-total-size⎇, Args {@i[array]⎇]
@f[array-total-size] returns the total number of elements in the @i[array],
calculated as the product of all the dimensions.
@lisp
(array-total-size @i[x])
   @EQ (apply #'* (array-dimensions @i[x]))
   @EQ (reduce #'* (array-dimensions @i[x]))
@endlisp
Note that the total size of a zero-dimensional array is @f[1].
The total size of a one-dimensional array is calculated without regard
for any fill pointer.
@Enddefun

@Defun[Fun {array-in-bounds-p⎇, Args {@i[array] @rest @i[subscripts]⎇]
This predicate checks whether the @i[subscripts] are all
legal subscripts for @i[array].  The predicate is true if they
are all legal; otherwise it is false.  The @i[subscripts] must be integers.
The number of @i[subscripts] supplied must equal the rank of the array.
Like @f[aref], @f[array-in-bounds-p] ignores fill pointers.
@Enddefun

@Defun[Fun {array-row-major-index⎇, Args {@i[array] @rest @i[subscripts]⎇]
This function takes an array and valid subscripts for the array
and returns a single non-negative integer less than the total size
of the array that identifies the
accessed element in the row-major ordering of the elements.
The number of @i[subscripts] supplied must equal the rank of the array.
Each subscript must be a non-negative integer less than the
corresponding array dimension.
Like @f[aref], @f[array-row-major-index] ignores fill pointers.

A possible definition of @f[array-row-major-index], with no error-checking,
would be
@lisp
(defun array-row-major-index (a @rest subscripts)
  (apply #'+ (maplist #'(lambda (x y)
			  (* (car x) (apply #'* (cdr y))))
		      subscripts
		      (array-dimensions a))))
@endlisp
For a one-dimensional array, the result of @f[array-row-major-index]
always equals the supplied subscript.
@Enddefun

@Defun[Fun {adjustable-array-p⎇, Args {@i[array]⎇]
This predicate is true if the argument (which must be an array)
is adjustable, and otherwise is false.
@Enddefun

@Section[Functions on Arrays of Bits]

The functions described in this section operate only
on arrays of bits, that is, specialized arrays whose elements
are all @f[0] or @f[1].

@Defun[Fun {bit⎇, Args {@i[bit-array] @rest @i[subscripts]⎇]
@Defun1[Fun {sbit⎇, Args {@i[simple-bit-array] @rest @i[subscripts]⎇]
@f[bit] is exactly like @Funref[aref] but requires an array of bits,
that is, one of type @f[(array bit)].
The result will always be @f[0] or @f[1].

@f[sbit] is like @f[bit] but additionally requires that the first
argument be a @i[simple] array (see section @ref[ARRAY-TYPE-SECTION]).

Note that @f[bit] and @f[sbit], unlike @Funref[char] and @Funref[schar],
allow the first argument to be an array of any rank.

@Macref[setf] may be used with @f[bit] or @f[sbit] to destructively replace
a bit-array element with a new value.

@f[bit] and @f[sbit] are identical to @Funref[aref] except for the
more specific type requirements on the first argument.
In some implementations of @clisp,
@f[bit] may be faster than @f[aref] in situations where it is applicable,
and @f[sbit] may similarly be faster than @f[bit].
@Enddefun

@Defun[Fun {bit-and⎇, Args {@i[bit-array1] @i[bit-array-2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-ior⎇,Args {@i[bit-array1] @i[bit-array-2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-xor⎇, Args {@i[bit-array1] @i[bit-array-2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-eqv⎇, Args {@i[bit-array1] @i[bit-array-2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-nand⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-nor⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-andc1⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-andc2⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-orc1⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
@Defun1[Fun {bit-orc2⎇, Args {@i[bit-array1] @i[bit-array2] @optional @i[result-bit-array]⎇]
These functions perform bit-wise logical operations on bit-arrays.
All of the arguments to any of these functions must be bit-arrays
of the same rank and dimensions.
The result is a bit-array of matching rank and dimensions,
such that any given bit of the result
is produced by operating on corresponding bits from each of the arguments.

If the third argument is @false or omitted, a new array is created
to contain the result.  If the third argument is a bit-array,
the result is destructively placed into that array.  If the third
argument is @true, then the first argument is also used as the third
argument; that is, the result is placed back in the first array.

The following table indicates what the result bit is for each operation
as a function of the two corresponding argument bits.
@Lisp
@Tabset[+1.1 in, +.3 in, +.3 in, +.3 in, +.3 in]
@Mline[]
@>@i[argument1]@f[  ]@\0@\0@\1@\1
@ux[@>@i[argument2]@f[  ]@\0@\1@\0@\1@\@i[Operation name]]
bit-and@\0@\0@\0@\1@\@r[and]
bit-ior@\0@\1@\1@\1@\@r[inclusive or]
bit-xor@\0@\1@\1@\0@\@r[exclusive or]
bit-eqv@\1@\0@\0@\1@\@r[equivalence (exclusive nor)]
bit-nand@\1@\1@\1@\0@\@r[not-and]
bit-nor@\1@\0@\0@\0@\@r[not-or]
bit-andc1@\0@\1@\0@\0@\@r[and complement of @i[argument1] with @i[argument2]]
bit-andc2@\0@\0@\1@\0@\@r[and @i[argument1] with complement of @i[argument2]]
bit-orc1@\1@\1@\0@\1@\@r[or complement of @i[argument1] with @i[argument2]]
bit-orc2@\1@\0@\1@\1@\@r[or @i[argument1] with complement of @i[argument2]]
@Mline[]
@Endlisp
For example:
@lisp
(bit-and #*1100 #*1010) @EV #*1000
(bit-xor #*1100 #*1010) @EV #*0110
(bit-andc1 #*1100 #*1010) @EV #*0100
@Endlisp
See @Funref[logand] and related functions.
@Enddefun

@Defun[Fun {bit-not⎇, Args {@i[bit-array] @optional @i[result-bit-array]⎇]
The first argument must be an array of bits.  A bit-array
of matching rank and dimensions is returned that contains
a copy of the argument
with all the bits inverted.
See @Funref[lognot].

If the second argument is @false or omitted, a new array is created
to contain the result.  If the second argument is a bit-array,
the result is destructively placed into that array.  If the second
argument is @true, then the first argument is also used as the second
argument; that is, the result is placed back in the first array.
@Enddefun

@Section[Fill Pointers]
@Label[FILL-POINTER]

Several functions for manipulating a @Def[fill pointer] are provided
in @clisp
to make it easy to incrementally fill in the contents of a vector
and, more generally, to allow efficient varying of the length of a vector.
For example, a string with a fill pointer has most of the characteristics
of a @pl1 varying string.

The fill pointer is a non-negative integer no larger than the total
number of elements in the vector (as returned by @Funref[array-dimension]);
it is the number of ``active'' or ``filled-in'' elements in the vector.
The fill pointer constitutes the ``active length'' of the vector;
all vector elements whose index is less than the fill pointer are
active, and the others are inactive.
Nearly all functions that operate on the contents of a vector
will operate only on the active elements.  An important exception
is @Funref[aref], which can be used to access any vector element
whether in the active region of the vector or not.  It is important
to note that vector elements not in the active region are still considered
part of the vector.
@Implementation{An implication of this rule is that
vector elements outside the active region may not be garbage-collected.⎇

Only vectors (one-dimensional arrays) may have fill pointers;
multidimensional arrays may not.  (Note, however, that one can create
a multidimensional array that is @i[displaced] to a vector that has
a fill pointer.)

@Defun[Fun {array-has-fill-pointer-p⎇, Args {@i[array]⎇]
The argument must be an array.  @f[array-has-fill-pointer-p] returns
@true if the array has a fill pointer, and otherwise returns @false.
Note that @f[array-has-fill-pointer-p] always returns @false if
the @i[array] is not one-dimensional.
@Enddefun

@Defun[Fun {fill-pointer⎇, Args {@i[vector]⎇]
The fill pointer of @i[vector] is returned.  It is an error if
the @i[vector] does not have a fill pointer.

@Macref[setf] may be used with @f[fill-pointer] to change the fill pointer
of a vector.  The fill pointer of a vector must always be an integer
between zero and the size of the vector (inclusive).
@Enddefun

@Defun[Fun {vector-push⎇, Args {@i[new-element] @i[vector]⎇]
@i[vector] must be a one-dimensional array that has a fill pointer,
and @i[new-element] may be any object.  @f[vector-push] attempts to store
@i[new-element] in the element of the vector designated by the fill
pointer, and to increase the fill pointer by one.  If the fill pointer does
not designate an element of the vector (specifically, when it gets too
big), it is unaffected and
@f[vector-push] returns @false.  Otherwise, the store and increment take
place and @f[vector-push] returns the @i[former] value of the fill pointer
(one less than the one it leaves in the vector); thus the value of
@f[vector-push] is the index of the new element pushed.
@Enddefun

@Defun[Fun {vector-push-extend⎇, Args {@i[new-element] @i[vector] @optional @i[extension]⎇]
@f[vector-push-extend] is just like @f[vector-push] except
that if the fill pointer gets too large, the vector is extended (using
@Funref[adjust-array]) so that it can contain more elements.
If, however, the vector is not adjustable, then @f[vector-push-extend]
signals an error.
The optional argument @i[extension], which must be a positive
integer, is the minimum number of elements to be added to the vector if it
must be extended; it defaults to a ``reasonable'' implementation-dependent
value.
@Enddefun

@Defun[Fun {vector-pop⎇, Args {@i[vector]⎇]
@i[vector] must be a one-dimensional array that has a fill pointer.
If the fill pointer is zero, @f[vector-pop] signals an error.
Otherwise the fill pointer is decreased by one, and the vector element
designated by the new value of the fill pointer is returned.
@Enddefun

@Section[Changing the Dimensions of an Array]

This function may be used to resize or reshape an array.
Its options are similar to those of @f[make-array].

@Defun[Fun {adjust-array⎇, Args {@i[array] @i[new-dimensions]⎇, Keys = {[element-type][initial-element]⎇,
 Morekeys {[initial-contents][fill-pointer]⎇,
 YetMoreKeys {[displaced-to][displaced-index-offset]⎇]
@f[adjust-array] takes an array and a number of other arguments
as for @Funref[make-array].  The number of dimensions
specified by @i[new-dimensions] must equal the rank of @i[array].

@f[adjust-array] returns an array of the same type and rank as @i[array],
with the specified @i[new-dimensions].  In effect, the @i[array] argument
itself is modified to conform to the new specifications, but this may
be achieved either by modifying the @i[array] or by creating a new
array and modifying the @i[array] argument to be @i[displaced] to the
new array.

In the simplest case, one specifies only the @i[new-dimensions]
and possibly an @Kwd[initial-element] argument.
Those elements of @i[array] that
are still in bounds appear in the new array.  The elements of
the new array that are not in the bounds of @i[array] are initialized
to the @Kwd[initial-element]; if this argument is not provided,
then the initial contents of any new elements are undefined.

If @Kwd[element-type] is specified, then @i[array] must be such that it could have
been originally created with that type; otherwise an error is signalled.
Specifying @Kwd[element-type] to @f[adjust-array] serves only to require such an
error check.

If @Kwd[initial-contents] or @Kwd[displaced-to]
is specified, then it is treated as for
@f[make-array].  In this case none of the original contents of
@i[array] appears in the new array.

If @Kwd[fill-pointer] is specified, the fill pointer of the @i[array]
is reset as specified.  An error is signalled if @i[array] had no
fill pointer already.

@f[adjust-array] may, depending on the implementation and the arguments,
simply alter the given array or create and return a new one.
In the latter case the given array will be altered so as to be displaced
to the new array and have the given new dimensions.

It is not permitted to call @f[adjust-array] on an array that was not
created with the @Kwd[adjustable] option.  The predicate
@Funref[adjustable-array-p] may be used to determine whether or not
an array is adjustable.

If @f[adjust-array] is applied to an @i[array] that is displaced
to another array @i[x], then afterwards neither @i[array] nor the returned
result is displaced to @i[x] unless such displacement is explicitly
re-specified in the call to @f[adjust-array].

For example, suppose that the 4-by-4 array @f[m] looks like this:
@Lisp
#2A( ( alpha     beta      gamma     delta )
     ( epsilon   zeta      eta       theta )
     ( iota      kappa     lambda    mu    )
     ( nu        xi        omicron   pi    ) )
@endlisp
Then the result of
@lisp
(adjust-array m '(3 5) :initial-element 'baz)
@endlisp
is a 3-by-5 array with contents
@Lisp
@tabset[+1 in, +1 in, +1 in, +1 in]
#2A( ( alpha     beta      gamma     delta     baz )
     ( epsilon   zeta      eta       theta     baz )
     ( iota      kappa     lambda    mu        baz ) )
@endlisp
Note that if array @f[a] is created displaced to array @f[b] and subsequently
array @f[b] is given to @f[adjust-array], array @f[a] will still be
displaced to array @f[b]; the effects of this displacement and
the rule of row-major storage order must be taken into account.
@Enddefun